develop

The develop branch holds the very latest and greatest code we have to offer, as such it may be less stable. It corresponds to the develop.element.io CD platform.

staging

The staging branch corresponds to the very latest release regardless of whether it is an RC or not. Deployed to staging.element.io manually.

master

The master branch is the most stable as it is the very latest non-RC release. Deployed to app.element.io manually.

The matrix-js-sdk follows semver, most releases will bump the minor version number. Breaking changes will bump the major version number. Element Web & Element Desktop do not follow semver and always have matching version numbers. The patch version number is normally incremented for every release.

Release candidate

A normal release begins with a Release Candidate on the Tick phase of the release cycle, and may contain as many further RCs as are needed before the Tock phase of cycle. Each subsequent RC may add additional commits via any of the means of preparation.

A normal release is the most typical run-of-the-mill release, with at least one RC (Release Candidate) followed by a FINAL release. The typical cadence for these is every 2 weeks we'll do a new initial RC, then the following week we'll do that release cycle's FINAL release with sometimes more RCs in between, as needed.

Final

A normal release culminates with a Final release on the Tock phase of the cycle. This may be merely shipping the very latest RC with an adjusted version number, but can also include (hopefully small) additional changes present on staging if they are deemed safe to skip an RC.

Hotfix / Security

This is an accelerated type of release which sits somewhere between RC and Final. They tend to contain few patches delta from the previous release but also skip any form of RC and in the case of Security the patch lands on GitHub only moments prior. For all intents and purposes they are the same as a Final release but with a different purpose.

You should become release rabbit on the day after the last full release. For that week, it's your job to keep an eye on the Releases room and see whether any issues marked X-Release-Blocker are opened, or were already open. You should chase people to fix them, so that on RC day you can make the release.

If release-blocking issues are still open, you need to delay the release until they are fixed or reclassified.

There are two labels for tracking release blockers.

X-Release-Blocker

This label applied to an issue means we cannot ship a release affected by the specific issue. This means we cannot cut branches for an RC but security & hotfix releases may still be fine.

X-Upcoming-Release-Blocker

This label applied to an issue means that the next (read: not current) release cycle will be affected by the specific issue. This label will automagically convert to X-Release-Blocker at the conclusion of a full release.

This release process revolves around our main repositories:

• Element Desktop
• Element Web
• Matrix JS SDK

We own other repositories, but they have more ad-hoc releases and are not part of the bi-weekly cycle:

• https://github.com/matrix-org/matrix-web-i18n/
• https://github.com/matrix-org/matrix-react-sdk-module-api

• You must be part of the 2 Releasers GitHub groups:
  • https://github.com/orgs/element-hq/teams/element-web-releasers
  • https://github.com/orgs/matrix-org/teams/element-web-releasers
• You will need access to the VPN (docs) to be able to follow the instructions under Deploy below.
• You will need the ability to SSH in to the production machines to be able to follow the instructions under Deploy below. Ensure that your SSH key has a non-empty passphrase, and you registered your SSH key with Ops. Log a ticket at https://github.com/matrix-org/matrix-ansible-private and ask for:
  • Two-factor authentication to be set up on your SSH key. (This is needed to get access to production).
  • SSH access to horme (staging.element.io and app.element.io)
  • Permission to sudo on horme as the user element
• You need "jumphost" configuration in your local ~/.ssh/config. This should have been set up as part of your onboarding.

flowchart TD
    P[[Prepare staging branches]]
    P --> R1

    subgraph Releasing
        R1[[Releasing matrix-js-sdk]]
        R2[[Releasing element-web]]
        R3[[Releasing element-desktop]]

        R1 --> R2 --> R3
    end

    R3 --> D1

    subgraph Deploying
        D1[\Deploy staging.element.io/]
        D2[\Check dockerhub/]
        D3[\Deploy app.element.io/]
        D4[\Check desktop package/]

        D1 --> D2 --> D
        D{FINAL?}
        D -->|Yes| D3 --> D4
    end

    D -->|No| H1
    D4 --> H1

    subgraph Housekeeping
        H1[\Update topics/]
        H2[\Announce/]
        H3[\Archive done column/]
        H4[\Add diary entry/]
        H5[\Renovate/]

        H1 --> H2 --> H

        H{FINAL?}
        H -->|Yes| H3 --> H4 --> DONE
        H -->|No| H5
    end

    DONE([You are done!])
    H5 --> DONE

With wording like:

Element Web v1.11.24 is here!

This version adds ... and fixes bugs ...

Check it out at app.element.io, in Element Desktop, or from Docker Hub. Changelog and more details at https://github.com/element-hq/element-web/releases/tag/v1.11.24